home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / dnssd / servicebrowser.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  7.6 KB  |  228 lines
  1. /* This file is part of the KDE project
  2.  *
  3.  * Copyright (C) 2004 Jakub Stachowski <qbast@go2.pl>
  4.  *
  5.  * This library is free software; you can redistribute it and/or
  6.  * modify it under the terms of the GNU Library General Public
  7.  * License as published by the Free Software Foundation; either
  8.  * version 2 of the License, or (at your option) any later version.
  9.  *
  10.  * This library is distributed in the hope that it will be useful,
  11.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13.  * Library General Public License for more details.
  14.  *
  15.  * You should have received a copy of the GNU Library General Public License
  16.  * along with this library; see the file COPYING.LIB.  If not, write to
  17.  * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18.  * Boston, MA 02110-1301, USA.
  19.  */
  20.  
  21. #ifndef DNSSDSERVICEBROWSER_H
  22. #define DNSSDSERVICEBROWSER_H
  23.  
  24. #include <qobject.h>
  25. #include <qdict.h>
  26. #include <dnssd/remoteservice.h>
  27.  
  28.  
  29. class QStringList;
  30. namespace DNSSD
  31. {
  32. class DomainBrowser;
  33. class ServiceBrowserPrivate;
  34.  
  35. /**
  36. Most important class for applications that want to discover specific services on network.
  37. Suppose that you need list of web servers running. Example:
  38.  
  39. \code
  40. DNSSD::ServiceBrowser* browser = new DNSSD::ServiceBrowser("_http._tcp");
  41. connect(browser,SIGNAL(serviceAdded(RemoteService::Ptr)),this,SLOT(addService(RemoteService::Ptr)));
  42. connect(browser,SIGNAL(serviceRemoved(RemoteService::Ptr)),this,SLOT(delService(RemoteService::Ptr)));
  43. browser->startBrowse();
  44. \endcode
  45.  
  46. In above example addService will be called for every web server already running or just appearing
  47. on network and delService will be called when server is stopped. Because no DomainBrowser was passed
  48. to constructor, domains configured by user will be searched.
  49.  
  50.  
  51. @author Jakub Stachowski
  52. @short Browsing for specific type of services or all available service types
  53.  */
  54. class KDNSSD_EXPORT ServiceBrowser : public QObject
  55. {
  56.     Q_OBJECT
  57. public:
  58.     /**
  59.     @li AutoDelete -  DomainBrowser object passes in constructor should be deleted when ServiceBrowser is deleted
  60.     @li AutoResolve - after disovering new service it will be resolved and then
  61.     reported with serviceAdded() signal. It raises network usage by resolving all services,
  62.     so use it only when necessary.
  63.      */
  64.     enum Flags {
  65.     AutoDelete =1,
  66.     AutoResolve = 2
  67.     };
  68.  
  69.     /**
  70.     Availability of DNS-SD services.
  71.     @li Working - available
  72.     @li Stopped - not available because mdnsd daemon is not running. 
  73.     @li Unsupported - not available because KDE was compiled without DNS-SD support
  74.     */
  75.     enum State { Working, Stopped, Unsupported };
  76.  
  77.     /**
  78.     ServiceBrowser constructor.
  79.  
  80.     @param types List of service types to browse for (example: "_http._tcp").
  81.     Can also be DNSSD::ServicesBrowser::AllServices to specify "metaquery" for all service types
  82.     present on network
  83.     @param domains DomainBrowser object used to specify domains to browse. You do not have to connect
  84.     its domainAdded() signal - it will be done automatically. You can left this parameter as NULL
  85.     for default domains.
  86.     @param flags One or more values from #Flags
  87.  
  88.     @since 3.5
  89.     @todo KDE4: set default values for domains and flags
  90.      */
  91.     ServiceBrowser(const QStringList& types,DomainBrowser* domains,int flags);
  92.  
  93.     /**
  94.     The same as above, but allows only one service type
  95.     @param type Type of services to browse for
  96.     @param domains  DomainBrowser object used to specify domains to browse. You do not have to connect its domainAdded() signal - it will be done automatically. You can left this parameter as NULL for default domains.
  97.     @param autoResolve auto resolve, if set
  98.     @deprecated use previous constructor instead
  99.      */
  100.     ServiceBrowser(const QString& type,DomainBrowser* domains=0,bool autoResolve=false);
  101.  
  102.     /**
  103.     Overloaded constructor used to create browser for one domain
  104.  
  105.     @param type Type of services to browse for
  106.     @param domain Domain name. You can add more domains later using addDomain and remove them
  107.     with removeDomain
  108.     @param flags One or more values from #Flags. AutoDelete flag has no effect
  109.     @since 3.5
  110.      */
  111.     ServiceBrowser(const QString& type,const QString& domain, int flags);
  112.  
  113.     /**
  114.     @deprecated user previous constructor instead
  115.      */
  116.     ServiceBrowser(const QString& type,const QString& domain, bool autoResolve=false);
  117.  
  118.     ~ServiceBrowser();
  119.  
  120.     /**
  121.     Returns list of services
  122.      */
  123.     const QValueList<RemoteService::Ptr>& services() const;
  124.  
  125.     /**
  126.     Starts browsing for services.
  127.     To stop it just destroy the object.
  128.      */
  129.     virtual void startBrowse();
  130.  
  131.     /**
  132.     Return DomainBrowser containing domains being browsed. Valid object will returned
  133.     even if 'domains' parameters in constructor was set to NULL or single domain
  134.     constructor was used.
  135.      */
  136.     const DomainBrowser* browsedDomains() const;
  137.  
  138.     /**
  139.     Special service type to search for all available service types. Pass it as "type"
  140.     parameter to ServiceBrowser constructor.
  141.      */
  142.     static const QString AllServices;
  143.  
  144.     /**
  145.     Checks availability of DNS-SD services (this also covers publishing).
  146.  
  147.     If you use this function to report an error to the user, below is a suggestion
  148.     on how to word the errors:
  149.  
  150.     \code
  151.     switch(DNSSD::ServiceBrowser::isAvailable()) {
  152.       case DNSSD::ServiceBrowser::Working:
  153.         return "";
  154.           case DNSSD::ServiceBrowser::Stopped:
  155.             return i18n("<p>The Zeroconf daemon is not running. See the Service Discovery Handbook"
  156.                         " for more information.<br/>"
  157.                     "Other users will not see this system when browsing"
  158.                     " the network via zeroconf, but normal access will still work.</p>");
  159.           case DNSSD::ServiceBrowser::Unsupported:
  160.             return i18n("<p>Zeroconf support is not available in this version of KDE."
  161.                         " See the Service Discovery Handbook for more information.<br/>"
  162.                         "Other users will not see this system when browsing"
  163.                         " the network via zeroconf, but normal access will still work.</p>");
  164.           default:
  165.             return i18n("<p>Unknown error with Zeroconf.<br/>"
  166.                         "Other users will not see this system when browsing"
  167.                         " the network via zeroconf, but normal access will still work.</p>");
  168.         }
  169.     \endcode
  170.  
  171.      */
  172.     static const State isAvailable();
  173.  
  174. signals:
  175.     /**
  176.     Emitted when new service is discovered (or resolved
  177.     if autoresolve is set
  178.      */
  179.     void serviceAdded(DNSSD::RemoteService::Ptr);
  180.     /**
  181.     Emitted when service is no longer announced. RemoteService object
  182.     is deleted from services list and destroyed immediately after this
  183.     signal returns.
  184.      */
  185.     void serviceRemoved(DNSSD::RemoteService::Ptr);
  186.  
  187.     /**
  188.     Emitted when all services has been reported. This signal can be used
  189.     by application that just want to get list of currently available services
  190.     (similar to directory listing) and do not care about dynamic adding/removing
  191.     services later. This signal can be emitted many time: for example if new host
  192.     has been connected to network and is announcing some services interesting to
  193.     this ServiceBrowser, they will be reported by several serviceAdded() signals and
  194.     whole batch will be concluded by finished().
  195.      */
  196.     void finished();
  197.  
  198. public slots:
  199.     /**
  200.     Remove one domain from list of domains to browse
  201.      */
  202.     void removeDomain(const QString& domain);
  203.  
  204.     /**
  205.     Add new domain to browse
  206.      */
  207.     void addDomain(const QString& domain);
  208.  
  209. protected:
  210.     virtual void virtual_hook(int, void*);
  211. private:
  212.     ServiceBrowserPrivate *d;
  213.  
  214.     bool allFinished();
  215.     void init(const QStringList&, DomainBrowser*, int);
  216.     QValueList<RemoteService::Ptr>::Iterator findDuplicate(RemoteService::Ptr src);
  217. private slots:
  218.     void serviceResolved(bool success);
  219.     void gotNewService(DNSSD::RemoteService::Ptr);
  220.     void gotRemoveService(DNSSD::RemoteService::Ptr);
  221.     void queryFinished();
  222.  
  223. };
  224.  
  225. }
  226.  
  227. #endif
  228.